MEMORY SPACE FOR ASSEMBLER 

Vhen aasenbllng a very large prcKgrdm,, It la passible for the 

Assembler to rtrn out of memory space. There are two remfidleB co 
try when thla happens : 



Use the command -level swapping option to get lU 
Additional Eoemory space? 



uords of 



If the program uees "include" files, use the Filer's MCaXe 
comroiand to create a 4-block file named SYSTEM, SWAPDISK on the 
same diskeEte that contains the Aaaembler, Thla allows a seginenc 
of the AsaeEnblef to be swapped out onto the diiakette before the 
operating system aegnient that opena files la swapped In, 



FILE SPACE FOR ASSEMBLER 

When the code file is autotnatlcally aent to the workflle the 
default gize for the file is [*]■* In all other cases, the 
default 9l£e is [0|, i,^icti means that the code file will be 
allocated all of the largest space available on the diskette chat 
it la ient to> If there is only one available space on the 
diak^ette, the code file takes all of it« 

Thla can cause prablecns If the code file is on the boot diskette 
or on the same diskette used for the listing file* Ihe Assetabler 
requires some space on the boot diskette for temporary files, and 
will fall if the code file takes all of the space on the ^oot 
diskette. Likevlsei the Assembler will fall if It tries to 
create a listing file and the code file baa taken all the 
available spsce on the specified diskette. 

If you run Into these prablemfip specify a different dlekecte for 
the code file or the listing file, or apeeify a definite length 
for the code file that will leave eaough room for other required 
files. 
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INTRODUCTION 



The docuEient you are reading Is an addendum co cUe Apple II Faacal 
Operating Syatem Reference Manual . Most of the iCecns described are 
featuree that have been added to Che Dperating ay^tem since the 
printinig of this cnanual* Corre&tlone tp the Eunual also have been 
Included^ 



COMMAKD LEVEL 



EXEC FILES 

An exec file Is composed of a. series of coininands that have b-een 
stored In a text file. When an exec file Is executed, each coinniand 
Included In the file Is executed, juat as If you were typing the 
cotnmands froit the keyboard. Rxec files are often used to store 
aequences of contmanda that cmiat be entered into the syatera aver antJ 
over again. 

The following sections include an explanation of exec flleg and a 
detailed example demonstrating the creation, execution, and editing 
of an exec file- 



Using Exec Files 



To create an exec file, Type M for M(ake from the tnaln Coxmand 
level* You will be prompted 

NEW EXEC KAME: 

Next type the name you want to give to your exec file, foiloitflng 
the aame rules that govern the naming of other Pascal files* If no 
file size is specified, the file will be opened with eight blocks* 
Now you wl I 1 see the prompt 

TERMIKATOR=Z , CKAWGE IT? 

The tenninaEar is a character that Is uaed Co signify the beginning 
and end of an exec file. The terminator character that ia used to 
begin the file is automatically supplied by the system* The two 
terminator characters that end the file must he typed by the user* 
If you answer the above prompt by typing N for No, the system will 
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use & percent sign aa a tenDlnator. If you type Y, meaning that you 
vant Co change Ebe terminatgir chatacter, you will be aakgd 

NEW TERMINATOR: 

Whatever character you enter becomes the cermlnetsr character for 
that exec file* The system will accept any character as the 
teriDlnator character except the control characters CTRL-C, CTRL-S, 

GTRL-F, CTRL-8, CTRL-A, CTRL«Z, GTRL-E, and CTRL-W. 

The terralnator character that signals Che beginning of an exec file 
la Bupplled by the syatera^ Do not begin an exec file by typing the 
terminator character* If you do, the systen^supplied terminator 
Inmediately Eallcwed by your typed tenolnator will be interpreted as 
the end-of-flle signal and the eystem will close the e^sec file. 

Once the system knows what your terminator character Is, you can 

begin entering the series of coEnmands that will make up your exec 

file. ComiBanda will be exe:CuCed as you enter them. End Che exec 
file by cypl ng the terminator charac te r cui ce , 

When you are ready to execute your exec file, type K for eXecute 
from the main Coniniand level. When you are prompted 

EXECUTE WHAT FILE 7 

you should respond by typing 

EXEC/<filenane> 

The system will Inatantaneoualy perform the aeries of coramands 
listed In your exec file, flashing the prompta and your prevlQUsly- 
enCered responses as it 



When us 

able to 

through 

create 

MYFILE, 

returns 

without 

drive, 

diskett 



Ing an exec file, you cmisC make sure that the system will be 
go through EXACTLY the same sequence of events that It went 
when you created the exec file* For example, suppose you 

an exec file that enters the Flier, transfers the file 

TEXT from diskette OLDSTUF: to diskette NEWSTU?: and then 
to the fttaln Commanid level. If you later run your exec fLle 
recnovlng the original diskette MEWSTUFj Irom Its disk 

the systen uould find MVFILE,TEXT already present on thaC 

e. Conaequenclyt the system will ask 



REMOVE Ota NEWS TUF:HYFILE< TEXT BEFORE TRANSFER 7 
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Thl& is a queaclon chat was not asked when the exec file was 
created* The syatem will use as its response the next character In 

the exec file which. In this case, happens to be Q for CJult. In 
order for the syatem to remove a file under these conditlonis , it 
must receive en M for No as the respomse to the above queatlcn. 
Thus, the old version of MYFILE will not be removed and the new 
version of MYFILE, will not be traoaferred* Because the Q was used 
to respond to this question, the exec file never uses che Q to tjult 
the Filer and the exec file closes with the syateo! still at the 
Filer level. The lesson to be learned from this la that, when 
creating an exec file, you nuet make sure that the stepa the system 
goes through will not change from one execution to another. 

There are some conditions ujider which you may want to create your 
exec file using the Editor rather than the Make command* Suppose, 
for example, that you want to create an exec file that will transfer 
several files to the printer* If you were to u6e the Make comntand 
Co create the file^ it would he necessary for you to wait at yauT 
terminal while each of the files Is actually sent to the printer. A 
more sensible approach would be to create the exec file in Che 
Editor* Renember, however, that the exec file you create misc 
Include every character required by each command. Forgetting to 
Include a single key stroke, such as a carriage return j will prevent 
the proper execution of your exec file* If you do use the Editor Co 
create an exec file, make sure that you begin the file with a single 
tertuinator character and end the file with two terminator 
characters . 



The Editor will not put certain special characters, such a& CTRL-C, 
Into Its text* Thus you cannot use Che Editor to create an exec 
file that creates a text file* 

If you decide to edit an existing exec file, you will notice that 
certain characters, such as <baokspace>, are Included In the exec 
file but do not appear on the screen* For this reason exec files 
are often difficult to edit. ^ 

There Is no way to stop the execution of an exec file part way 
through except by pressing RESET, You can use CTRL-S to temporarily 
stop or freeze the output on the screen. CTRL-F flushes the output: 
Che program continues to run but its output is not sent to the 
screen or printer* 
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The keyboard ceLmalne ap^ti during the execution df an eitec file* 
Thus characters Chat are entered while an exec file Is running are 
saved and then used as console input once the exec file Is closed* 

If you us« the Make command to create an exec file on a diskette 
that already has a file with Che name you have given your *xec flle^ 
the system will ellndnate the original file when you close the new 
exec file* 

It Is not pennleslble to create an exec file from within another 
exec file. If you try, you will be warned 

NESTED EKEC COMMANDS ILLEGAL 

Aft«r you bgg this message, you taay continue entering commdnda into 
the exec file* 

If you are using an Apple with a standard 40-coluiim screen^ the 
control characters CTRL-S» CTRL'^F, CTRL-#, CTRL-A, and CTRL-Z* 
cannot be read Into an exec file* If you are u&tng a ConiraunicatlonB 
Card with your Apple to get upper and lowercase and an S0 column 
screen, CITlL-S, CTRi-F, and CTRL-@ cannot be read Into an exec file* 
Although all of thess characters Mill operate normally If used i^cn 
an exec file Is being created using the Make command, they vtll not 
be placed in the CKec file and chereforE will not be read when the 
file la fjcecuted. 

If you run a Pascal prograni while you are making an exec file, typed 
resporsea to any UNITHEAD procedures specifylnE unit 1 (CONSOLE: ) 
or unit 2 (SYSTEKH; ) are used by the Pascal program^ but are NOt 
stored in the exec file* The KlYPRESS function also vill cake its 
input from rhe console and not from the exec file. REAIl anid READLN 
procedures will take their Input from the exec file. 

The system error routine will close an open exec file If an error 
occurs \rtiilg the ayatem is getting console input from the exec file. 
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An Example Exec File 



Suppose you want to create an exec file that crunches whatever 
diskette is in Drive #5 and then sets the Prefix to the name of the 
diskette in that drive* 

Prompt: NEW EXEC NAHEr 

Response: NEW3TUF: UPDATE 

You have Just created an exec file named UPDATE. TEXT that will be 
eaved on diskette NERSTUFt . Because you have not specified a 
si£e^ the fiyBteiH will set aside eight flocks- Next you will be 
asked: 



Prompt; TERMlNATOR-%, CHANGE IT? 

Response: N 

Entering this response tells the system that the terminator 
character^ the character used Co signal the beginning and end of the 
exec file^ vill reiaain the percent aign* 

You now are ready to enter the list of coinimindg that will riake up 
your exec file* 



Keystroke 

F 
m 

#5: 



<cr> 

P 
#5: 

<cr> 
Q 



Explanatioii 

Enter Filer 

Execute Krunch command 

Response to prompt CRUNCH WHAT TOLUKE ? 

telling the system to crunch 

the diskette in drive ^^ 
Carriage Return ending the volume mitnber 
ReBponse to prompt 

FROM END OF DISK, BLOCK 280 ? CY OR N5 
Execute Prefix comioand 
Response to prompt /■ 

PREFIX TITLES BY WHAT VOL ? 
Carriage Return ending the volume number 
Exit from the filer 
Terminator characters indicating to the 

system Ch^t the exec file is complece! 
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Note that each of these coisniattds is executed In the normal fasTiion 
when Ic is typed Into the exec file* Thus, after carrying aut the 
ahove list of coramanda, the diskette in drive fl5 will be crunched 
and the Prefix will be act to the name of the diskette In drive ^5» 

When you are ready to es^ecute the exec file, type X for eXecute 
followed hy 

EXEC7NEWSTUF : UPDATE 

You then will see the syatetn enter the Filer, Krunch the diskette In 
Dritfe #5, set the Prefix, and return to the Command level i 

If you later decide that you want to luodlfy your exec file, you can 
read it Into the Editor Juat as you would any textflle* The file 
NEWSTUF: UPDATE would look like this: 



YPfl5: 



Note that the percent sign that begins the file is automatically 
supplied by the system. Also note that the system supplies two 
additional terminator characters at the end of the exec file. 

Suppose that, ^en creating the above exec file, you responded to 

the praopt 

KRUKCH WHAT FILE? 

by typing a dollar sign instead of a number sign* After you 
realized your mistake, you backspaced once and typed the correct 
response C 1^5: ). If you read this veraion of the exec file into 
the Editor, the display will look exactly like the display in 
the example shown above* In reality^ however, the exec file 
contains these characters 

!£FK5<bB>#5:<cr> 
yp*5:<cr> 

azxxx 

where <tiB> represents a backspace and <cr> represents n carriage 
return. Now suppose that you decide that you want to Krunch the 
diskette In Volume #Ai instead of the diskette in Volume fl3: 
First you might decide to delete the 5, If you loove the cursor so 
that it sits on the 5 , type D for Delete, and then move the right 
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arrow one Bpace* the first line of the display should now look like 
thiat 

%FlC$ff5: 
This same line In the exec file actually contains these charactera: 

The character deleted, a backspace character, was the fifth 
character In the exec file, NOT the fifth character displayed on the 
screen. Notice that the dollar algn ch&racter that had been typed 
over by the backspace in the ofiginal exec file now appears on the 
display. Ojice the backspace character Is removed, characters can be 
inserted and deleted norraally- 

In general. It Is quite difficult to edit exec files. If you must 
do BO, rememher that certain characters, guch aa backspace, CTRL-G^ 
snd curaor-movlng characters, will not show up on the display even 
though they are present in an e^^ec file. 

THE SWAPPING OPTION 

Apple Pascal now Includes a Swapping option that allows you to 
maTcimlse the space available In the Apple's meraory. The following 
chart illustrates memory availability for a codeflle at execution 
time on a standard Apple II with 40 coluon screen: 



Swapping On Swapping Off 



Approxifflate 
maxlTiym 
user program 
space in bytes 



39W 



377{lfS 



The Swapping option Is set to OFF each tlnie the ayateia is booted. 
To change the Swapping option* type S from the Command level. You 
will either see the ntessage 

SWAPPING IS ON 



SWAPPlfTG IS OFF 
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depending on Swapplng'a cuttenC state* Below this will be tbe 
question 

TOGGLE SWAPPING? 

Typing A Y changes Swapping from OH to OFF or vice verss. Typing an 
N leaves Swapping In Its current state- When Swapping la turned 
on, a portion of tbe operating flyHtera nmst be read In from the boot 
diskette each tlrae you open or close a file* This reeultfl in a 
slight slowdown of the system* 

TWO' new procedures, SWAPON and SWAFOFF^ make It possible to turn 
swapping on and off frora within a program* These procedures are 
part of the CHAINSTUFF unit and are described In the section on 
chaining In the Addendum to the Appls Pascal Language Reference 
Manual « 



^J 



Oslng a standard Apple II wlch 40 column screen, Che nai^lmum size 
file that can be read into the Editor with Swapping set to OFF Is 34 
blocks* The TTOxlmutn size file that can be read into the Editor with 
Swapping set to OK is 40 blockiH. Before reading a file that Is 
longer than 34 blocks into the Editor, caalte sure chat Swapping Is 
turned on. If you cry Co read a file into Che Editor that exceeds 
the Editor's limit, you will see the n^esage; 



ERROR; BUFFER OVERFLOW t 



PLEASE PRESS <SPACEBAR> TO CONTINUE 



When you press the spacebar, a& much of the file as can fit will be 
read Into the Editor* At this point you should use the Quit and 
Exit commanda to leave the Editor; next set Swapping to ON. Now 
when you read the file into the Editor, the complete file will be 
available for editing. 

The Faacal Operating System Manual say a on page 98 that the oaximuni 
size Editor file la about 18400 bytes or 38 diskette blocks* This 
figure does not Include the 2 blocks of Information that are 
Included in the first two blocks of any text file. To find out the 
actual amount of space that a file occupies^ use the Filer's List 
directory or Extended directory list comcnand- 

One drive users: When Swapping Is set to OW, all operations muat be 
performed with the boot diskette In the disk drive. The only 
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exception is the execution of Filer comnands. The Filer, once 
called} causes the operating ayatem to remain entirely tnglde Che 
Apple's TDeiQory. Thus, once the Filer has been called, the boot 
diskette can be replaced by any other dlBkette containing files Chat 
need Co be accessed* 

UPPER AND LOWERCASE CAPABILITY 

In normal operation, all letters typed on the Apple II keyboard are 
uppercase letters and all letters are displayed on the screen aa 
capitals, regardless of whether they are actually uppercase or 
lowercase* Version 1*1 of Apple Pascal allows you to alter this 
nonnal node in two ways: 

You can shift the keyboard into lowercase (and back into uppercase) 
at any time* 

You can cause uppercase letters to be displayed on the screen in 
reverse video (black on white) to distinguish them from lowercase 
letters. 

Note that only letters are affected by these features* Also, note 
that you can now Qtea.te a. file conitainifLg lowercase letters &.B Well 
as uppercase^ If you then print this file on a printer that has 
upper and lowercase capability^ true upper and lowercase characters 
will be printed. 

Keyboard Case Control 

By turning the "reverse video node" OH, you cause uppercase letter* 
to be displayed in reverse video Vhlle lowercase letters are 
displayed in normal video. The control characters CTRL-E and 
CtRL-W are used to turn reverse video OK and change the case of 
letters typed on the keyboard. They can be uied from any level of 
the aystem, Including the Editor. 

- Typing CTRL-E (foe "Enable") on the keyboard turns the reverse 
video node ONp and changes the case of the keyboard from upper 
to lowercase or vice versa. Thus It la like the "shift lock" 
key on a typewriter. / 

- Typing CTRL-W (for "Word") on the keyboard turns the reverse 
video mode ON, and forces the keyboard into uppercase for Che 
nexc character typed* After Che next character ia typed, the 
keyboard Is forced into louercase. This is useful when you 
want to capitalize the firet letter of a word- 
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Notice that since CTRL-E and CTRL-W turn reverse video ON, chey 
provide all Che control you need except for turning reverse video 
OFF again. 

Other Control Characters 

The control characters CTRL-R and CTRL-T control the video raode 
from any level of the systen except the Editor: 

- Typing CTRL-R (for "Reverse") on the keyboard turns Che 
reverse video mode ON. Note that thlg does not change the 
keyboard caee^ all letters typed on the keyboard are still 
uppercase unless CTRL-E or CTRL-W is used to change caee- 

- Typing CTRL-T (for "Turn off") on the keyboard reatoceia normal 
operation: that Is, it turns reyerse video cnodf OFF and also 
forces the keyboard Into uppercase. 

Ttote that CTRL-T and CTHL-R have no effect when yon are In the 

Editor. 



Using Upper and Lowercase 



The best Way to get acquainted with thi^ c^pabill Cy Is Eo experiment 
with It. Try entering the Editor and tyfjing I for Insert. Now type 
CTHL-E followed by aonie text. The letters you are typing will 
appear In normal video* Now type CTRL-E again. AH subsequent 
alphabetic characters appear in reverse video. Next type CTRL-W 
followed by a word. The first letter appears In reverse video while 
the reisalnlng letters appear in normal video. If, at this point i 
you save youc file and then print It, ajl characters except those 
thac appeared in reverse video will be printed In lowercase, ^ter 
you exit from the editor^ the system ^11 still be in reverse video 
mode- To return the systera to standard uppercase only mode, type 

cniL-T. 



RESET 

The discussion of RESET that appears on page 10 of the Apple Pascal 
Operating System Reference^ Hanual is not correct* Preaalng the 

Apple's RESET key now ^oes^ a~"cold boot" of the system* It Is 

equivalent to turning off the power and turning It on again* After 

you have pressed RESET, you will have to reboot the systeen using the 
normal startup procedure. 
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THE FILER: THE PREFIX COMMAND 

The Fxeflx conmand is normally used to set Che Prefix to a specified 
volume name* You can, however, use the Prefix coTnmand to set the 
Prefix to the volume nunber of a disk drive* This feature allows 
yau to change diskettes In a given drive without having to change 
the Prefix each time a different diskette Is placed In that drive. 
To use the Prefix coimnand In this way i the Prefix tmiHt be set wheA 
no diskette la placed In the drive that you wish to designate as the 
Prefix disk drive. If, when you are setting the Prefix, a diskette 
Ifl In the drive that is designated as the Prefix disk drive, the 
Prefix will be aet to the name of the diskette In that drive. 

EXAKFLE 

Suppose that yau want to set the Prefix to Volume #5* With your 
boot diskette in the boot drive and no diskette In VoluDe ^S, enter 
the Filer and type P for PreflK- 



Pronpt : 



PREFIX TITLES BY VmAT VOL 7 



Response: #5 

You have just set the Prefix to whatever diskette is plated in Drive 
#5. Suppose chat you now place diskette LISTA: In drive ?5 and type 
E for Extended directory Hat followed by a colon* The directory of 
LISTA: will appear on the screen. Now remove diskette LISTA: and 
t«place it with diskette LISTB; « If you again type E for Extended 
directory list followed by a colon, the directory of LISTB: will 
appear on the screen* 



THE EDITOR: FIKD AND REPLACE 

The Find and Replace comcnainds now have the capability to locate a 
string of characters within text regardless of whether the 
characters In the text are of the same case as the characters In the 
target string that you have specified. To utilize this option, type 
F for Find or R for Replace followed by U for Upper and Lowercase. 
Next enter the etrlng, set off by delimiters^ that you want to Find 
or Replace, To use the Find command to find the next occurrence of 
the previously specified string without regard to case^ type 
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F for Find. Then, when the Flni3 ptonpt line appears ^ type US 
use the Replace conmLand to replace the ne^t occur rettce pf the 
previously specified string sdchout regard to upper and lowercase, 
type R. Then, When the Replace prompt line appea^s^ type US . 

Thla option aay be uaed to locale etrlnga af characters that were 
eatered ueing the reveree video option described earlier, 

EXAMPLE 1 : 

Suppose you have a file containing the following text: 

Frogran String; 
Begin 

write ('The rain in Spain' )j 

vrlceln (' falls loslnly on the plain.') 
End. 



To 



and that y^ou want to ua£ the Find cotninand to move the cursor to 
each occurrence of the word "the". When at the Edit level, type F 
for Find, When you see the Find prompt, type the followlna 

U/the/ 

When you type the last / , the cursor will move Immediately to the 
apace foUcjwlng the "e" in the first occurrence of the word "the" 
even though. In this Instance, the first occurrence of the word 
"the" begins with an uppercase letter* To move the cursar to 
the next occurrence of "the" type F again. When you see the Find 
prompt line this time* type U S . This tells the system to find the 
sarne string as specified previously, regardless of whether the 
characters In the string are In upper or lowercase. If you were 
only to type S when the Find proiapt line was on the screen, the 
sysCeiD would find the next occurrence of "the" containing only 
lowercaae characters since that la the string you apeclfled in the 
original Fin^ command* 
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Example 2: 

Suppose you have the following program 

program chocolate; 
begin 

wrlteln (' Checkmate Chocolate la the best '}; 

Wfiteln (' thocolate In the whole wide world, ^) 
end« 

and tJiat you want to replace every occurrence of the word 
"chocolate" with the word "peanut butter". From the Editot type R 
for Replace* When the Replace prompt line appears type the 
following: 

u/chocolate/ /peanut butter/ 

All three oecurreneea of the word "chocolate" will he replaced by 
the word "peanut butter". Note that "peanut butter" will appear In 
lowercase regardless of whether the word It replaces is In upper or 
louercase . 



THE 6502 ASSEMBLER 



ERROR MESSAGES 

The following new AsEembler error cnessage has been added: 



50(3: General aEsembler error 



ASSEMBLY LISTINGS 

tfote that you can use the Editor to examine (at edit) a listing 
file produced by the ^semblerj after the Editor loads the 
listing file;, you should do a Replace opGration on the entire 
file to replace all CTRL-L'b with CTRL-H's- To do this* type the 
following characters; 

/R/GTRL-1//CTRL-M/ 

(The CTRL-L's that the Assembler puts in the listing are "page 
e:]ect" chsracters Intended for controlling output on a printer*) 
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